Cloudinary のバージョン項目って？キャッシュの仕組みと理解しよう
画像や動画の変換や最適化、管理が簡単にできる SaaS、Cloudinary 。その配信 URL にはバージョンが含まれることがあります。
このバージョンをどうするかは、Cloudinary 導入時に決めるべき大事な構成の一つなので、きちんと理解していただきたいです。
Cloudinary の配信 URL （おさらい）
Cloudinaryの配信URLは下記のような構成です。
https://res.cloudinary.com/[クラウド名]/[リソースタイプ]/[タイプ]/[署名]/[変換パラメータ]/[バージョン]/[パブリックID].[フォーマット]
◆詳しくはこちらのブログを参照してください。
変換パラメータの後、パブリックIDの前に「バージョン」がありますね。
バージョンとは
これは何かというと、同じ名前でファイルを更新した場合を想定して使われる、アセットのバージョンです。
vと数字を組み合わせた形式で、デフォルトではファイルの更新時間のUNIXタイムスタンプの数字が続きます。
例えば以下の img1 について、最初に画像をアップロードしたのは “Created” の表示にある 2021年7月20日 ですが、別の画像に置き換えました。それが、”Last replaced” の表示にある2022年5月12日です。この画像のURLをコンソール上でコピーすると、以下のようになっています。
https://res.cloudinary.com/CLOUD-NAME/image/upload/v1652343795/travel/img1.jpg
このうちv1652343795がバージョンで、エポック秒の1652343795を変換すると 2022年5月12日 10:23:15 、更新日時を示すことが分かります。
ですが、配信URLにバージョン項目を含めるのは任意です。
先のURLでは/v1652343795の部分を削ってしまっても、あるいは/v12345といった数字に書き換えても、同じ画像を表示することができます。
バージョンはなぜ必要？
バージョンを含めなくても配信できるなら余計な項目は入れたくないと思うでしょう。
しかし、バージョンを使用することは推奨されています。
先ほどの例で、画像を更新する前と後の画像URLはそれぞれ次のようになります。
- バージョンを使う場合：更新前後でURLが異なるので、ウェブサイト上のURLを差し替え、ユーザは新規URLにアクセスすることになります。
# 更新前の画像URL（既存URL） https://res.cloudinary.com/CLOUD-NAME/image/upload/v1652343795/travel/img1.jpg # 更新後の画像URL（新規URL） https://res.cloudinary.com/CLOUD-NAME/image/upload/v1626788112/travel/img1.jpg
- バージョンを使わない場合：更新前後とも全く同じURLを使います。古い画像のキャッシュが残っていると、ユーザは更新後の画像へ直ちにアクセスすることができません。
# 更新前後とも同じ画像URL https://res.cloudinary.com/CLOUD-NAME/image/upload/travel/img1.jpg
Cloudinary CDN のキャッシュは Cloudinary から無効化することもできますが、環境によっては他にも中間キャッシュがあり、より複雑な可能性があります。
バージョンを使うことで、新しいURLでキャッシュ問題を気にせずただちに更新した画像を配信させることができるのです。
ここで勘違いしてはならないのが、古いバージョン番号のURLでその古い画像にいつまでもアクセスできるというわけではないということです。キャッシュが切れたら、古い画像はCloudinaryにはもう存在しないので、アクセス済みの古いURLも更新後の画像を返すようになります。 1
バージョン項目は、あくまで異なるURLを発行してキャッシュを避けるためのものです。
Cloudinary で扱われるバージョンの形式
上の説明からすると、長い数字でなくても、v1、v2でいいじゃないかと思われるでしょう。
はい、それでもただちに更新画像を配信するという目的は達成されます。が、残念ながら Cloudinary が API やコンソールで発行する URL のバージョン形式をカスタマイズすることはできません。
またCDNキャッシュ消去することを考慮するなら、Cloudinary が扱う以下いずれかのバージョン形式に従うべきです。
- オプション１：フォルダ配下のアセットは v1 、ルート直下のアセットはバージョンなし
- APIで画像URLを取得した場合に出力される形式
- この形式を使う場合、設定「Invalidate versioned URLs」に Disabled を選択（デフォルト）
- オプション２：すべてのアセットで、バージョンなし
- この形式を使う場合、サポートヘ依頼（設定「Invalidate versioned URLs」は無効化され、非表示となる）
- オプション３：すべてのアセットで、最新のフルバージョン（更新日時のUNIX時間）
- APIで画像アップロード時や詳細取得時のレスポンス、およびコンソールで画像URLを取得した場合の形式
- この形式を使う場合、設定「Invalidate versioned URLs」に Enabled を選択
(注): Surrogate key 機能が有効なアカウント（詳細は後述）では、設定「Invalidate versioned URLs」は非表示になっています。
以下、Python API で実行した場合の例です。
# オプション１の例：画像URLを取得（フォルダ配下）
>>> cloudinary.CloudinaryImage("samples/cloudinary-group.jpg").image(
... height=60,
... quality="auto",
... secure=True)
'<img height="60" src="https://res.cloudinary.com/CLOUD-NAME/image/upload/h_60,q_auto/v1/samples/cloudinary-group.jpg"/>'
# オプション１の例：画像URLを取得（ルート直下）
>>> cloudinary.CloudinaryImage("sample.jpg").image(
... height=60,
... quality="auto",
... secure=True)
'<img height="60" src="https://res.cloudinary.com/CLOUD-NAME/image/upload/h_60,q_auto/sample.jpg"/>'
# オプション３の例：画像アップロード
>>> cloudinary.uploader.upload(
... "image.png",
... public_id="fol1/test"
... )
{'asset_id': '1d93a06d32f8ac5980de476f783c33a6', 'public_id': 'test1/test.png', 'version': 1652729753, 'version_id': '79789f0e692211b649bf6f244eaae5f5', 'signature': 'd86f56e8e486fa306c8473be09a13430a114b01c', 'width': 128, 'height': 128, 'format': 'png', 'resource_type': 'image', 'created_at': '2022-05-16T19:35:53Z', 'tags': [], 'bytes': 6132, 'type': 'upload', 'etag': '24e299e6a25c86bff939cd09e20e700c', 'placeholder': False, 'url': 'http://res.cloudinary.com/CLOUD_NAME/image/upload/v1652729753/fol1/test.png', 'secure_url': 'https://res.cloudinary.com/CLOUD-NAME/image/upload/v1652729753/fol1/test.png', 'folder': 'fol1', 'access_mode': 'public', 'original_filename': 'image', 'api_key': '123456789012345'}
>>>
Cloudianry がキャッシュ消去するバージョン形式
Cloudinary のほとんどのアカウント環境では、"surrogate key invalidation” という機能が有効です。この場合、多くのケースでバージョン形式を気にすることなくアセットに紐づくすべてのキャッシュが消去されます。
これには、上述のオプションに限らず v123 といったランダムな数字も対象です。
2020年にCloudinaryで導入された機能で、2020年12月以降に作成されたアカウントでは必ず対応しています。本機能を有効にしたい場合やアカウントで本機能が有効かどうか確認したい場合は、サポートへ連絡してください。
一方で、これが有効でないレガシー環境では、特定のバージョン形式のキャッシュのみ（設定に基づいて前述3つのオプションいずれか）が消去されます。
ただし残念ながら、現時点ではこの surrogate key 機能は一部ケースをサポートしておらず、その場合はレガシー環境と同様の動きとなります。
Surrogate key invalidation 環境
- コンソール上でのアセットの更新・削除時に、あらゆるバージョン形式のURLのキャッシュを消去する
- Upload APIで invalidate=true オプションを指定した更新時に、あらゆるバージョン形式のURLのキャッシュを消去する
- 設定「Invalidate versioned URLs」は非表示となる
- ただし、Admin API など本機能が未サポートの操作時は、従来選択したオプション設定でレガシーと同様の動きとなる（現状の設定はサポート経由で確認・変更可能）
レガシー環境
- コンソール上でのアセットの更新・削除時、またはAPIで invalidate=true オプションを指定した操作時に、特定のバージョン形式のURLのキャッシュを消去する
- この「特定のバージョン形式」は、コンソールの Settings > Upload > 「Invalidate versioned URLs」の設定に基づく（オプション2はサポートへ依頼）
- また署名付きURLのキャッシュ無効化を有効にしたい場合、サポートへ依頼
例）設定が Disabled（デフォルト）の場合、以下の通りオプション１の形式のURLのみキャッシュが削除されます。
無効化される:
https://~/image/upload/sample.jpg
https://~/image/upload/v1/folder1/sample.jpg
無効化されない:
https://~/image/upload/sample.jpg (オプション２のため)
https://~/image/upload/v1/sample.jpg (いずれのオプションにも該当しないため)
https://~/image/upload/v1593602134/sample.jpg (オプション３のため)
FAQ
Q. バージョン情報は含めなくてもよいか？
A. バージョン値がどの数字でも、あるいはなくても、配信することは可能です。
ですが、同じファイル名で画像が更新される可能性がある場合には、バージョンを使うことが推奨されています。
（例えば、バージョンなしのURLで画像Aに一度アクセスすると、同じ名前で画像Bに差し替えても、画像Aのキャッシュが残るため、URLは古い画像Aを表示し続けます。このため、画像Bを表示させるには、アップロード日時に応じたバージョンを含む新しいURLにアクセスするか、APIでアップロード時にキャッシュ消去するオプションを付与する必要があります。）
Q. コンソールでコピーするリンクやAPIの出力結果で、バージョン項目を含めないようにすることができるか？
A. APIやコンソールで出力されるURLについては、現時点で設定でコントロールできず、バージョン値を含まないURLを出力させることはできません。
コンソールやAPIで画像URLを発行すると、前述のオプション１と３のように場合によって自動的にバージョンが含まれてしまうため、不要な場合は手動でバージョン値を取り除いてください。
おしまい
Cloudinaryに限らず、バージョンを使ってURLを更新する手法は一般的に推奨されています。
バージョン管理されたURLはキャッシュストラテジに役立ちます。バージョン管理されたURLは、キャッシュに保存された応答を簡単に無効化できるため、優れた方法です。（参考：HTTPキャッシュを使用して不要なネットワーク要求を防ぐ）
同じパブリックID（フォルダ・ファイル名）で画像を更新するというユースケースがある場合、基本的にオプション３に従うことがベストです。
また、URLを固定したい場合でも、Cloudinaryの処理を正常に行わせるために、オプション１を選択するのが無難で安全といえます。
